
<!DOCTYPE html>
<!--

    Copyright (c) 2017, 2019 Oracle and/or its affiliates. All rights reserved.

    This program and the accompanying materials are made available under the
    terms of the Eclipse Public License v. 2.0, which is available at
    http://www.eclipse.org/legal/epl-2.0.

    This Source Code may also be made available under the following Secondary
    Licenses when the conditions for such availability set forth in the
    Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
    version 2 with the GNU Classpath Exception, which is available at
    https://www.gnu.org/software/classpath/license.html.

    SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0

-->
<!-- Portions Copyright [2019] [Payara Foundation and/or its affiliates] -->
<html lang="en">
  <head>
    <meta charset="utf-8"/>
    <title>setup-ssh</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link href="css/style.css" rel="stylesheet">
    <script src="https://use.fontawesome.com/96c4d89611.js"></script>
  </head>
  <body>
<table id="doc-title" cellspacing="0" cellpadding="0">
  <tr>
  <td align="left" valign="top">
  <b>setup-ssh</b><br />
  </td>
  </tr>
</table>
<hr />

<table width="90%" id="top-nav" cellspacing="0" cellpadding="0">
	<colgroup>
		<col width="12%"/>
		<col width="12%"/>
		<col width="*"/>
	</colgroup>
	<tr>
		<td align="left">
		<a href="setup-local-dcom.html">
			<span class="vector-font"><i class="fa fa-arrow-circle-left" aria-hidden="true"></i></span>
			<span style="position:relative;top:-2px;">Previous</span>
		</a>
		</td>

		<td align="left">
		<a href="set-web-context-param.html">
			<span class=" vector-font"><i class="fa fa-arrow-circle-right vector-font" aria-hidden="true"></i></span>
			<span style="position:relative;top:-2px;">Next</span>
		</a>
		</td>

		<td align="right">
		<a href="toc.html">
			<span class=" vector-font"><i class="fa fa-list vector-font" aria-hidden="true"></i></span>
			<span style="position:relative;top:-2px;">Contents</span>
		</a>
		</td>
	</tr>
</table>


<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p><a id="setup-ssh-1"></a><a id="GSRFM00229"></a><a id="setup-ssh"></a></p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_setup_ssh">setup-ssh</h2>
<div class="sectionbody">
<div class="paragraph">
<p>sets up an SSH key on specified hosts</p>
</div>
<div id="sthref2074" class="paragraph">
<p>Synopsis</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-oac_no_warn" data-lang="oac_no_warn">asadmin [asadmin-options] setup-ssh [--help]
[--sshport ssh-port] [--sshuser ssh-user]
[--sshkeyfile ssh-keyfile] [--sshpublickeyfile ssh-public-keyfile]
[--generatekey={false|true}]
host-list</code></pre>
</div>
</div>
<div id="sthref2075" class="paragraph">
<p>Description</p>
</div>
<div class="paragraph">
<p>The <code>setup-ssh</code> subcommand sets up a secure shell (SSH) key on the hosts
that are specified as the operand of the subcommand. This key enables
\{product---name} to use public-key authentication for authentication of
the user&#8217;s SSH login on remote hosts.</p>
</div>
<div class="paragraph">
<p>SSH ensures that \{product---name} clusters that span multiple hosts can
be administered centrally. When a user runs a subcommand for cluster
administration that acts on multiple hosts, the subcommand is propagated
from the domain administration server (DAS) host to remote hosts. To
propagate subcommands that act on a \{product---name} instance that is
not running, or on a node where no instances are running,
\{product---name} uses SSH. SSH provides confidentiality and security
for data that is exchanged between the DAS and remote hosts.</p>
</div>
<div class="paragraph">
<p>Public-key authentication uses an SSH key pair that comprises the
following keys:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>A private key, which is stored in a secure location on the DAS host
and which may be protected with a passphrase</p>
</li>
<li>
<p>The public key, which is stored on all the remote hosts with which the
DAS communicates</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The subcommand does not require any configuration information from the
DAS and does not modify the configuration of the DAS.</p>
</div>
<div class="paragraph">
<p>This subcommand is supported in local mode only.</p>
</div>
<div class="paragraph">
<p>Prerequisites for Using the <code>setup-ssh</code> Subcommand</p>
</div>
<div class="paragraph">
<p>To use the <code>setup-ssh</code> subcommand, the SSH user must be able to use SSH
to log in to remote hosts where SSH is to be set up. Specifically, the
following prerequisites must be met:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The
<code>ssh</code> client is installed on the DAS host and is accessible through the DAS
user&#8217;s path.</p>
</li>
<li>
<p>The
<code>sshd</code> daemon is installed and running on all hosts where an SSH key is to be
set up.</p>
</li>
<li>
<p>The user that the <code>--sshuser</code> option specifies has an SSH login on all
hosts where an SSH key is to be set up.</p>
</li>
<li>
<p>The
<code>ssh-keygen</code>
utility is installed on the DAS host either at the default location or
in a location that is defined in the DAS user&#8217;s path.</p>
</li>
<li>
<p>On Windows systems, the SSH package for <a href="http://www.cygwin.com/">Cygwin</a>
(<a href="http://www.cygwin.com/" class="bare">http://www.cygwin.com/</a>) or an <a href="http://www.mkssoftware.com/">MKS Software</a>
(<a href="http://www.mkssoftware.com/" class="bare">http://www.mkssoftware.com/</a>) toolkit that provides SSH is installed.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Behavior of the <code>setup-ssh</code> Subcommand</p>
</div>
<div class="paragraph">
<p>The subcommand sets up SSH connectivity between the DAS host and remote
hosts by automating the following tasks:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Generating an SSH key pair. If no SSH key pair exists, the default
behavior of the subcommand is to prompt the user to generate an SSH key
pair. The SSH key pair is generated without an encryption passphrase. If
a passphrase-protected key pair is required, the key pair must be
generated manually by using the SSH
command <code>ssh-keygen</code></p>
</li>
<li>
<p>Distributing the public key. The subcommand appends the content of the
public key file to the user-home`/.ssh/authorized_keys` file on each
remote host. By default, the subcommand locates the public key file in
the user-home`/.ssh` directory on the host where the subcommand is run.
If the user-home`/.ssh/authorized_keys` file does not exist on a host,
the subcommand creates the file. user-home is the user&#8217;s home directory
on a host.<br>
To distribute the public key, authentication of the user&#8217;s SSH login is
required. If the private key is protected by a passphrase, the
passphrase is also required. By default, the subcommand prompts the user
for the password and, if necessary, the passphrase. To distribute the
public key without being prompted, run the subcommand as follows:</p>
<div class="ulist">
<ul>
<li>
<p>Set the <code>--interactive</code> option of the
<a href="asadmin.html#asadmin-1m"><code>asadmin</code>(1M)</a> utility to <code>false</code>.</p>
</li>
<li>
<p>Set the <code>--passwordfile</code> option of the <code>asadmin</code> utility to a file in
which the <code>AS_ADMIN_SSHPASSWORD</code> entry specifies the SSH user&#8217;s password
for logging in to the specified hosts.</p>
</li>
<li>
<p>If a passphrase is required, ensure that the file that
<code>--passwordfile</code> option of the <code>asadmin</code> utility specifies also contains
an entry for <code>AS_ADMIN_SSHKEYPASSPHRASE</code>.<br>
If public key authentication is already set up on a host, the subcommand
informs the user that public key authentication is already set up and
does not distribute the key to the host.</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
<div id="sthref2076" class="paragraph">
<p>Options</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">asadmin-options</dt>
<dd>
<p>Options for the <code>asadmin</code> utility. For information about these
options, see the <a href="asadmin.html#asadmin-1m"><code>asadmin</code>(1M)</a> help page.</p>
</dd>
<dt class="hdlist1"><code>--help</code></dt>
<dt class="hdlist1"><code>-?</code></dt>
<dd>
<p>Displays the help text for the subcommand.</p>
</dd>
<dt class="hdlist1"><code>--sshport</code></dt>
<dd>
<p>The port to use for SSH connections to the host where SSH is being set
up. The default is 22.</p>
</dd>
<dt class="hdlist1"><code>--sshuser</code></dt>
<dd>
<p>The SSH user on the remote host that is to run the process for setting
up SSH on that host. The default is the user that is running this
subcommand. To ensure that the DAS can read this user&#8217;s SSH private
key file, specify the user that is running the DAS process.</p>
</dd>
<dt class="hdlist1"><code>--sshkeyfile</code></dt>
<dd>
<p>The absolute path to the SSH private key file for user that the
<code>--sshuser</code> option specifies. This file is used for authentication to
the <code>sshd</code> daemon on the host.<br>
The user that is running this subcommand must be able to reach the
path to the key file and read the key file.<br>
The default is a key file in the user&#8217;s <code>.ssh</code> directory on the host
where the subcommand is run. If multiple key files are found, the
subcommand uses the following order of preference:<br></p>
<div class="olist arabic">
<ol class="arabic">
<li>
<p><code>id_rsa</code></p>
</li>
<li>
<p><code>id_dsa</code></p>
</li>
<li>
<p><code>identity</code></p>
</li>
</ol>
</div>
</dd>
<dt class="hdlist1"><code>--sshpublickeyfile</code></dt>
<dd>
<p>The absolute path to the SSH public key file for user that the
<code>--sshuser</code> option specifies. The content of the public key file is
appended to the user&#8217;s <code>.ssh/authorized_keys</code> file on each host where
SSH is being set up. If the <code>.ssh/authorized_keys</code> file does not exist
on a host, the subcommand creates the file.<br>
The user that is running this subcommand must be able to reach the
path to the key file and read the key file.<br>
The default is a key file in the user&#8217;s <code>.ssh</code> directory on the host
where the subcommand is run. If multiple key files are found, the
subcommand uses the following order of preference:<br></p>
<div class="olist arabic">
<ol class="arabic">
<li>
<p><code>id_rsa.pub</code></p>
</li>
<li>
<p><code>id_dsa.pub</code></p>
</li>
<li>
<p><code>identity.pub</code></p>
</li>
</ol>
</div>
</dd>
<dt class="hdlist1"><code>--generatekey</code></dt>
<dd>
<p>Specifies whether the subcommand generates the SSH key files without
prompting the user.<br>
Possible values are as follows:<br></p>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>true</code></dt>
<dd>
<p>The subcommand generates the SSH key files without prompting the
user.</p>
</dd>
<dt class="hdlist1"><code>false</code></dt>
<dd>
<p>The behavior of the subcommand depends on whether the SSH key files
exist:<br></p>
<div class="ulist">
<ul>
<li>
<p>If the SSH key files exist, the subcommand does not generate the
files.</p>
</li>
<li>
<p>If the SSH key files do not exist, the behavior of the subcommand
depends on the value of the <code>--interactive</code> option of the <code>asadmin</code>
utility:</p>
<div class="ulist">
<ul>
<li>
<p>If the <code>--interactive</code> option is <code>true</code>, the subcommand prompts
the user to create the files.</p>
</li>
<li>
<p>If the <code>--interactive</code> option is <code>false</code>, the subcommand fails.<br>
This value is the default.</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
</dd>
</dl>
</div>
</dd>
</dl>
</div>
<div id="sthref2077" class="paragraph">
<p>Operands</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">host-list</dt>
<dd>
<p>A space-separated list of the names of the hosts where an SSH key is
to be set up.</p>
</dd>
</dl>
</div>
<div id="sthref2078" class="paragraph">
<p>Examples</p>
</div>
<div class="paragraph">
<p><a id="GSRFM751"></a><a id="sthref2079"></a></p>
</div>
<div class="paragraph">
<p>Example 1   Setting Up an SSH Key</p>
</div>
<div class="paragraph">
<p>This example sets up an SSH key for the user <code>gfuser</code> on the hosts
<code>sj03</code> and <code>sj04</code>. The key file is not generated but is copied from the
user&#8217;s <code>.ssh</code> directory on the host where the subcommand is running.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-oac_no_warn" data-lang="oac_no_warn">asadmin&gt; setup-ssh sj03 sj04
Enter SSH password for gfuser@sj03&gt;
Copied keyfile /home/gfuser/.ssh/id_rsa.pub to gfuser@sj03
Successfully connected to gfuser@sj03 using keyfile /home/gfuser/.ssh/id_rsa
Copied keyfile /home/gfuser/.ssh/id_rsa.pub to gfuser@sj04
Successfully connected to gfuser@sj04 using keyfile /home/gfuser/.ssh/id_rsa
Command setup-ssh executed successfully.</code></pre>
</div>
</div>
<div class="paragraph">
<p><a id="GSRFM752"></a><a id="sthref2080"></a></p>
</div>
<div class="paragraph">
<p>Example 2   Generating and Setting Up an SSH Key</p>
</div>
<div class="paragraph">
<p>This example generates and sets up an SSH key for the user <code>gfuser</code> on
the hosts <code>sua01</code> and <code>sua02</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-oac_no_warn" data-lang="oac_no_warn">asadmin&gt; setup-ssh --generatekey=true sua01 sua02
Enter SSH password for gfuser@sua01&gt;
Created directory /home/gfuser/.ssh
/usr/bin/ssh-keygen successfully generated the identification /home/gfuser/.ssh/id_rsa
Copied keyfile /home/gfuser/.ssh/id_rsa.pub to gfuser@sua01
Successfully connected to gfuser@sua01 using keyfile /home/gfuser/.ssh/id_rsa
Copied keyfile /home/gfuser/.ssh/id_rsa.pub to gfuser@sua02
Successfully connected to gfuser@sua02 using keyfile /home/gfuser/.ssh/id_rsa
Command setup-ssh executed successfully.</code></pre>
</div>
</div>
<div id="sthref2081" class="paragraph">
<p>Exit Status</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">0</dt>
<dd>
<p>command executed successfully</p>
</dd>
<dt class="hdlist1">1</dt>
<dd>
<p>error in executing the command</p>
</dd>
</dl>
</div>
<div id="sthref2082" class="paragraph">
<p>See Also</p>
</div>
<div class="paragraph">
<p><a href="asadmin.html#asadmin-1m"><code>asadmin</code>(1M)</a></p>
</div>
<div class="paragraph">
<p>Cygwin Information and Installation (<code>http://www.cygwin.com/</code>), MKS
Software (<code>http://www.mkssoftware.com/</code>)</p>
</div>
</div>
</div>

<hr />

<table width="90%" id="bottom-nav" cellspacing="0" cellpadding="0">
	<colgroup>
		<col width="12%"/>
		<col width="12%"/>
		<col width="*"/>
	</colgroup>
	<tr>		
		<td align="left">
		<a href="setup-local-dcom.html">
			<span class=" vector-font"><i class="fa fa-arrow-circle-left" aria-hidden="true"></i></span>
			<span style="position:relative;top:-2px;">Previous</span>
		</a>
		</td>

		<td align="left">
		<a href="set-web-context-param.html">
			<span class="vector-font"><i class="fa fa-arrow-circle-right vector-font" aria-hidden="true"></i></span>
			<span style="position:relative;top:-2px;">Next</span>
		</a>
		</td>

		<td align="right">
		<a href="toc.html">
			<span class="vector-font"><i class="fa fa-list vector-font" aria-hidden="true"></i></span>
			<span style="position:relative;top:-2px;">Contents</span>
		</a>
		</td>
	</tr>
</table>

<span id="copyright">
        <img src="/resource/reference/img/eclipse_foundation_logo_tiny.png" height="20px" alt="Eclipse Foundation Logo" align="top"/>&nbsp;            
        <span >Copyright&nbsp;&copy;&nbsp;2019,&nbsp;Oracle&nbsp;and/or&nbsp;its&nbsp;affiliates.&nbsp;All&nbsp;rights&nbsp;reserved.</span>
</span>

</body>
</html>
